Skip to content

Add transform context for annotating compiler optimizations#216

Merged
gnidan merged 7 commits into
mainfrom
transform-context
Jul 16, 2026
Merged

Add transform context for annotating compiler optimizations#216
gnidan merged 7 commits into
mainfrom
transform-context

Conversation

@gnidan

@gnidan gnidan commented Jul 2, 2026

Copy link
Copy Markdown
Member

This PR adds a transform context that records which compiler optimizations produced an instruction, and wires it end to end — from the bugc emitters to the tracer — so a debugger can tell compiler-synthesized code from the source the user wrote.

Format

  • Adds the transform context — a flat sibling key listing the optimization passes applied to an instruction (fold, coalesce, tailcall, inline), with its schema, TypeScript type, and spec page. The identifier set is extensible.
  • Specifies the inlined-call virtual-activation contract — an inlined call keeps an invoke/return bracket with the code target omitted and marks the spliced body with transform: ["inline"], so a debugger reconstructs a virtual activation without a real frame.
  • Correlates activations with an activation identifier — the opening invoke and its closing return/revert carry the same value, pairing a call with its return independent of trace order.

Implementation

  • Emits the four transforms from bugc through a shared Ir.Utils.addTransform helper: fold on constant folding, coalesce on read-write merging, tailcall on the TCO back-edge, and inline from a new function-inlining pass that splices eligible leaf callees into their call sites and brackets the body with a virtual invoke/return.
  • Reconstructs inline and tail-call virtual activations in the tracer's call stack.
  • Surfaces transform annotations in the tracer's instruction list, with an O0–O3 optimizer-level selector to watch them appear as the level rises.
  • Documents the transforms with tracing examples and a trace-playground walkthrough (tail-call and inlining showcases).

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-16 04:45 UTC

@gnidan
gnidan force-pushed the transform-context branch 11 times, most recently from 2a8509d to 0e59810 Compare July 16, 2026 04:16
gnidan added 4 commits July 16, 2026 00:21
Introduce the `transform` context: a flat sibling key on an instruction
listing the optimization passes (fold, coalesce, tailcall, inline) the
compiler applied to it, so a debugger can distinguish
compiler-synthesized code from the source the user wrote.

Adds the schema, the format TypeScript type, and the spec page, and
registers the context page in the docs schema index.
Emit `transform: ["tailcall"]` on the TCO back-edge JUMP, alongside the
invoke/return pair it already carries, so a debugger sees the pair as a
tail-call-optimized back-edge rather than a real frame push/pop and does
not invent a spurious frame.

Render it in the tracer drawer — an optimizer-level (O0-O3) selector and a
tail-call-aware call stack — and document it with a tracing example and a
walkthrough homed in the trace playground.

Introduces the shared `Ir.Utils.addTransform` helper — the fold, coalesce,
and inline emitters all route through it — and the transform-emission test
file (`transform-contexts.test.ts`, with the `countTransform` helper),
covering the tailcall marker: absent at O0/O1, present at O2/O3.
Mark constant-folded values with `transform: ["fold"]` through a shared
`addTransform` helper, so the tracer can show a value as a
compile-time-evaluated constant rather than source. The marker composes
with later passes into a multiset (e.g. `["fold", "coalesce"]`).
Mark the SHL/OR field-packing sequence produced by read-write merging
with `transform: ["coalesce"]`, so a packed-storage write reads as
compiler-synthesized rather than source the user wrote. Composes with a
folded value into `["fold", "coalesce"]`.
@gnidan
gnidan force-pushed the transform-context branch from 0e59810 to c8355db Compare July 16, 2026 04:22
gnidan added 3 commits July 16, 2026 00:28
Add the function-inlining transform end to end:

- spec the inlined-call virtual-activation contract — push/pop pairing
  via the virtual invoke/return versus the per-instruction `inline`
  membership marker;
- add the bugc inlining pass (level 2): splice eligible leaf callees into
  their call sites, emit `transform: ["inline"]` on the spliced body, and
  bracket it with a virtual invoke/return; bracket those boundary ops in
  evmgen so the activation nests correctly;
- reconstruct the inline virtual activations in the tracer's call stack;
- add the inlining showcase examples and the trace-playground section.
Correlate activations with an `activation` identifier on invoke, return,
and revert: the invoke that opens an activation and the return or revert
that closes it carry the same value, so a debugger pairs a call with its
return independent of trace order. It lives inside the
invoke/return/revert object, keeping a tail call's two facts flat without
a `gather`.
Show the tailcall and inline transform annotations inline in the tracer's
instruction list, so the optimizer passes applied to each instruction are
visible as you step through the trace.
@gnidan
gnidan force-pushed the transform-context branch from c8355db to e08afea Compare July 16, 2026 04:28
@gnidan
gnidan marked this pull request as ready for review July 16, 2026 04:40
@gnidan
gnidan merged commit a36e919 into main Jul 16, 2026
5 checks passed
@gnidan
gnidan deleted the transform-context branch July 16, 2026 04:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant